package com.gobang.service;

import com.gobang.domain.dto.LoginRequestDTO;
import com.gobang.domain.vo.LoginResponseVO;

/**
 * 认证授权业务服务接口
 * 负责用户登录认证、会话管理和安全验证
 * 
 * @author System
 * @since 1.0.0
 */
public interface AuthService {

    /**
     * 用户登录
     * 验证用户名密码，生成JWT Token，建立用户会话
     *
     * @param loginRequest 登录请求数据
     * @return 登录响应信息（包含Token和用户信息）
     */
    LoginResponseVO login(LoginRequestDTO loginRequest);

    /**
     * 用户登出
     * 销毁用户会话，清理缓存信息
     *
     * @param userId 用户ID
     * @return 登出是否成功
     */
    boolean logout(Long userId);

    /**
     * 验证Token有效性
     * 检查Token是否有效且未过期
     *
     * @param token JWT Token
     * @return Token是否有效
     */
    boolean validateToken(String token);

    /**
     * 刷新Token
     * 在Token即将过期时生成新的Token
     *
     * @param token 原Token
     * @return 新Token，失败返回null
     */
    String refreshToken(String token);

    /**
     * 从Token中获取用户ID
     *
     * @param token JWT Token
     * @return 用户ID
     */
    Long getUserIdFromToken(String token);

    /**
     * 检查用户是否在线
     * 基于Redis缓存检查用户会话状态
     *
     * @param userId 用户ID
     * @return 是否在线
     */
    boolean isUserOnline(Long userId);
} 